#region License
/* ---------------------------------------------------------------- *
 *
 * This file is part of the Xcoordination Application Space
 * ("XcoAppSpace") http://www.xcoordination.com
 *
 * Copyright (C) 2009 Xcoordination http://www.xcoordination.com
 *
 * XcoAppSpace is free software; you can redistribute it and/or
 * modify it under the terms of version 2 of the GNU General
 * Public License as published by the Free Software Foundation.
 *
 * XcoAppSpace is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see http://www.gnu.org/licenses/
 * or write to the Free Software Foundation, Inc., 51 Franklin
 * Street, Fifth Floor, Boston, MA 02110-1301, USA.
 *
 * ---------------------------------------------------------------- */
#endregion

using System;
using System.Net;
using XcoAppSpaces.Contracts.Communication;
using XcoAppSpaces.Contracts.Worker;
using XcoAppSpaces.Core.Ports;

namespace XcoAppSpaces.Core
{
	/// <summary>
	/// Interface definition for the XcoAppSpace class, the main class of XcoAppSpaces.
	/// </summary>
	public interface IXcoAppSpace : IDisposable
	{
		/// <summary>
		/// Provides meta information about the XcoAppSpace instance, e.g. information about 
		/// running workers and communication services.
		/// </summary>
		XcoSpaceInfo Info { get; }

		/// <summary>
		/// The credentials that are used by the space to connect to remote workers.
		/// </summary>
		ICredentials Credentials { get; set; }

		/// <summary>
		/// The address of the space (that can be used by other spaces to connect to this space)
		/// </summary>
		string Address { get; }

		/// <summary>
		/// Port where errors are posted that occur during commmunication with Fother space instances
		/// and that have not been caught by causalities (e.g. errors during message deserialization 
		/// or security errors).
		/// </summary>
		Port<XcoCommunicationError> Errors { get; }

		/// <summary>
		/// Resolves an instance of the requested type with the given name from the local appspace.
		/// </summary>
		/// <typeparam name="TContract">The type that is requested.</typeparam>
		/// <returns>The resolved object.</returns>
		TContract Resolve<TContract>();

		/// <summary>
		/// Resolves worker of the requested type with the given name from the local appspace.
		/// </summary>
		/// <typeparam name="TContract">The type that is requested.</typeparam>
		/// <param name="name">The name of the object to retreive.</param>
		/// <returns>The resolved object.</returns>
		TContract Resolve<TContract>(string name);

		/// <summary>
		/// Runs a worker within the appspace. The worker is published so other appspace instances can connect to it.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <typeparam name="TImplementation">The implementation type of the worker (which must inherit from the contract type).</typeparam>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract, TImplementation>() 
			where TMessageContract : IPort
			where TImplementation : TMessageContract, new();

		/// <summary>
		/// Runs a worker within the appspace. The worker is published so other appspace instances can connect to it.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <typeparam name="TImplementation">The implementation type of the worker (which must inherit from the contract type).</typeparam>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract, TImplementation>(string name)
			where TMessageContract : IPort
			where TImplementation : TMessageContract, new();

		/// <summary>
		/// Runs a worker within the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <typeparam name="TImplementation">The implementation type of the worker (which must inherit from the contract type).</typeparam>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract, TImplementation>(PublishMode publish)
			where TMessageContract : IPort
			where TImplementation : TMessageContract, new();

		/// <summary>
		/// Runs a worker within the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <typeparam name="TImplementation">The implementation type of the worker (which must inherit from the contract type).</typeparam>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract, TImplementation>(PublishMode publish, string name)
			where TMessageContract : IPort
			where TImplementation : TMessageContract, new();

		/// <summary>
		/// Runs a worker within the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <typeparam name="TImplementation">The implementation type of the worker (which must inherit from the contract type).</typeparam>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <param name="options">Additional Port options, like the maximum degree of parallelism.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract, TImplementation>(PublishMode publish, string name, PortReceiverOptions options)
			where TMessageContract : IPort
			where TImplementation : TMessageContract, new();

		/// <summary>
		/// Runs a worker within the appspace.  The worker is published so other appspace instances can connect to it.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract>(TMessageContract worker)
			where TMessageContract : IPort;

		/// <summary>
		/// Runs a worker within the appspace.  The worker is published so other appspace instances can connect to it.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <param name="worker">The worker instance to run.</param>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract>(TMessageContract worker, string name)
			where TMessageContract : IPort;

		/// <summary>
		/// Runs a worker within the appspace. 
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <param name="worker">The worker instance to run.</param>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract>(TMessageContract worker, PublishMode publish)
			where TMessageContract : IPort;

		/// <summary>
		/// Runs a worker within the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <param name="worker">The worker instance to run.</param>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract>(TMessageContract worker, PublishMode publish, string name)
			where TMessageContract : IPort;

		/// <summary>
		/// Runs a worker within the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker, which must be an IPort (meaning it must be a CCR Port or PortSet).</typeparam>
		/// <param name="worker">The worker instance to run.</param>
		/// <param name="publish">Defines if the worker should be published so other appspace instances can connnect to it.</param>
		/// <param name="name">The name under which the worker should be registered.</param>
		/// <param name="options">Additional Port options, like the maximum degree of parallelism.</param>
		/// /// <returns>The worker instance that has been created.</returns>
		TMessageContract RunWorker<TMessageContract>(TMessageContract worker, PublishMode publish, string name, PortReceiverOptions options)
			where TMessageContract : IPort;

		/// <summary>
		/// Disposes the given worker instance and removes it from the appspace.
		/// </summary>
		/// <param name="worker">The worker to be removed.</param>
		void StopWorker(IPort worker);

		/// <summary>
		/// Disposes a worker instance and removes it from the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The type of the worker.</typeparam>
		void StopWorker<TMessageContract>()
			where TMessageContract : IPort;

		/// <summary>
		/// Disposes a worker instance and removes it from the appspace.
		/// </summary>
		/// <typeparam name="TMessageContract">The type of the worker.</typeparam>
		/// <param name="name">The name of the worker.</param>
		void StopWorker<TMessageContract>(string name)
			where TMessageContract : IPort;

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space.  After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(string workerAddress)
			where TMessageContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space. After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <param name="localName">The name under which the worker should be registered locally.</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(string workerAddress, string localName)
			where TMessageContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space. After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="commServiceName">The name of the communication service that should be used for communication with the worker.</param>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <param name="localName">The name under which the worker should be registered locally.</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(string commServiceName, string workerAddress, string localName)
			where TMessageContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space.  After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="publish">Defines if the created worker proxy should be published so other appspace instances can connnect to it, and by that use the appspace instance to connect to the original worker.</param>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(PublishMode publish, string workerAddress)
			where TMessageContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space. After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="publish">Defines if the created worker proxy should be published so other appspace instances can connnect to it, and by that use the appspace instance to connect to the original worker.</param>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <param name="localName">The name under which the worker should be registered locally.</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(PublishMode publish, string workerAddress, string localName)
			where TMessageContract : IPort, new();

		/// <summary>
		/// Establishes a connection to a worker that is running at a remote space, and registers
		/// the worker at the local space. After ConnectWorker is called, the worker to which the
		/// connection has been established is also available through the appspace's Resolve method.
		/// This method allows using addresses that are not displayable with a "hostname:port" pattern.
		/// </summary>
		/// <typeparam name="TMessageContract">The contract type of the worker.</typeparam>
		/// <param name="publish">Defines if the created worker proxy should be published so other appspace instances can connnect to it, and by that use the appspace instance to connect to the original worker.</param>
		/// <param name="commServiceName">The name of the communication service that should be used for communication with the worker.</param>
		/// <param name="workerAddress">The address of the worker in form "address/workername"</param>
		/// <param name="localName">The name under which the worker should be registered locally.</param>
		/// <returns>A worker contract instance that allows to post messages to the remote worker.</returns>
		TMessageContract ConnectWorker<TMessageContract>(PublishMode publish, string commServiceName, string workerAddress, string localName)
			where TMessageContract : IPort, new();
	}
}